Documentation In Comment Blocks

Docular parses your script files ( designated in your Grunt config ), and looks for documentation that live within blocked comments. A block comment looks like this:

/**
 * This is a block comment
 */

/**
 * This is a multi
 * line block comment
 */

Sample Documentation Within Comment Blocks

Here is an example of Docular documentation within comment blocks within a script file:

//this comment is ignored because it is not in a block

/**
 * @doc function
 * @name myModule.moduleSection:thisIsAFunction
 *
 * @description This function rules!
 *
 * This is still part of the description!!!
 */

var thisIsAFunction = function () {};

Summary

So here are a few points to note:

  1. Documentation is parsed as key value pairs
  2. Each @ represents a key. So @description designates the "description" key
  3. Text following the key on the same line and text on following lines before the next @ will be the value for that key
  4. Comments delimeted by // are not parsed so you can essentially separate your documentation comments from other inline comments that would best be suited for those scanning code instead of learning about your APIs.